home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dstebz.z / dstebz
Encoding:
Text File  |  2002-10-03  |  9.2 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDSSSSTTTTEEEEBBBBZZZZ((((3333SSSS))))                                                          DDDDSSSSTTTTEEEEBBBBZZZZ((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DSTEBZ - compute the eigenvalues of a symmetric tridiagonal matrix T
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      SUBROUTINE DSTEBZ( RANGE, ORDER, N, VL, VU, IL, IU, ABSTOL, D, E, M,
  13.                         NSPLIT, W, IBLOCK, ISPLIT, WORK, IWORK, INFO )
  14.  
  15.          CHARACTER      ORDER, RANGE
  16.  
  17.          INTEGER        IL, INFO, IU, M, N, NSPLIT
  18.  
  19.          DOUBLE         PRECISION ABSTOL, VL, VU
  20.  
  21.          INTEGER        IBLOCK( * ), ISPLIT( * ), IWORK( * )
  22.  
  23.          DOUBLE         PRECISION D( * ), E( * ), W( * ), WORK( * )
  24.  
  25. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  26.      These routines are part of the SCSL Scientific Library and can be loaded
  27.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  28.      directs the linker to use the multi-processor version of the library.
  29.  
  30.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  31.      4 bytes (32 bits). Another version of SCSL is available in which integers
  32.      are 8 bytes (64 bits).  This version allows the user access to larger
  33.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  34.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  35.      only one of the two versions; 4-byte integer and 8-byte integer library
  36.      calls cannot be mixed.
  37.  
  38. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  39.      DSTEBZ computes the eigenvalues of a symmetric tridiagonal matrix T. The
  40.      user may ask for all eigenvalues, all eigenvalues in the half-open
  41.      interval (VL, VU], or the IL-th through IU-th eigenvalues.
  42.  
  43.      To avoid overflow, the matrix must be scaled so that its
  44.      largest element is no greater than overflow**(1/2) *
  45.      underflow**(1/4) in absolute value, and for greatest
  46.      accuracy, it should not be much smaller than that.
  47.  
  48.      See W. Kahan "Accurate Eigenvalues of a Symmetric Tridiagonal Matrix",
  49.      Report CS41, Computer Science Dept., Stanford
  50.      University, July 21, 1966.
  51.  
  52.  
  53. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  54.      RANGE   (input) CHARACTER
  55.              = 'A': ("All")   all eigenvalues will be found.
  56.              = 'V': ("Value") all eigenvalues in the half-open interval (VL,
  57.              VU] will be found.  = 'I': ("Index") the IL-th through IU-th
  58.              eigenvalues (of the entire matrix) will be found.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDSSSSTTTTEEEEBBBBZZZZ((((3333SSSS))))                                                          DDDDSSSSTTTTEEEEBBBBZZZZ((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      ORDER   (input) CHARACTER
  75.              = 'B': ("By Block") the eigenvalues will be grouped by split-off
  76.              block (see IBLOCK, ISPLIT) and ordered from smallest to largest
  77.              within the block.  = 'E': ("Entire matrix") the eigenvalues for
  78.              the entire matrix will be ordered from smallest to largest.
  79.  
  80.      N       (input) INTEGER
  81.              The order of the tridiagonal matrix T.  N >= 0.
  82.  
  83.      VL      (input) DOUBLE PRECISION
  84.              VU      (input) DOUBLE PRECISION If RANGE='V', the lower and
  85.              upper bounds of the interval to be searched for eigenvalues.
  86.              Eigenvalues less than or equal to VL, or greater than VU, will
  87.              not be returned.  VL < VU.  Not referenced if RANGE = 'A' or 'I'.
  88.  
  89.      IL      (input) INTEGER
  90.              IU      (input) INTEGER If RANGE='I', the indices (in ascending
  91.              order) of the smallest and largest eigenvalues to be returned.  1
  92.              <= IL <= IU <= N, if N > 0; IL = 1 and IU = 0 if N = 0.  Not
  93.              referenced if RANGE = 'A' or 'V'.
  94.  
  95.      ABSTOL  (input) DOUBLE PRECISION
  96.              The absolute tolerance for the eigenvalues.  An eigenvalue (or
  97.              cluster) is considered to be located if it has been determined to
  98.              lie in an interval whose width is ABSTOL or less.  If ABSTOL is
  99.              less than or equal to zero, then ULP*|T| will be used, where |T|
  100.              means the 1-norm of T.
  101.  
  102.              Eigenvalues will be computed most accurately when ABSTOL is set
  103.              to twice the underflow threshold 2*DLAMCH('S'), not zero.
  104.  
  105.      D       (input) DOUBLE PRECISION array, dimension (N)
  106.              The n diagonal elements of the tridiagonal matrix T.
  107.  
  108.      E       (input) DOUBLE PRECISION array, dimension (N-1)
  109.              The (n-1) off-diagonal elements of the tridiagonal matrix T.
  110.  
  111.      M       (output) INTEGER
  112.              The actual number of eigenvalues found. 0 <= M <= N.  (See also
  113.              the description of INFO=2,3.)
  114.  
  115.      NSPLIT  (output) INTEGER
  116.              The number of diagonal blocks in the matrix T.  1 <= NSPLIT <= N.
  117.  
  118.      W       (output) DOUBLE PRECISION array, dimension (N)
  119.              On exit, the first M elements of W will contain the eigenvalues.
  120.              (DSTEBZ may use the remaining N-M elements as workspace.)
  121.  
  122.      IBLOCK  (output) INTEGER array, dimension (N)
  123.              At each row/column j where E(j) is zero or small, the matrix T is
  124.              considered to split into a block diagonal matrix.  On exit, if
  125.              INFO = 0, IBLOCK(i) specifies to which block (from 1 to the
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDSSSSTTTTEEEEBBBBZZZZ((((3333SSSS))))                                                          DDDDSSSSTTTTEEEEBBBBZZZZ((((3333SSSS))))
  137.  
  138.  
  139.  
  140.              number of blocks) the eigenvalue W(i) belongs.  (DSTEBZ may use
  141.              the remaining N-M elements as workspace.)
  142.  
  143.      ISPLIT  (output) INTEGER array, dimension (N)
  144.              The splitting points, at which T breaks up into submatrices.  The
  145.              first submatrix consists of rows/columns 1 to ISPLIT(1), the
  146.              second of rows/columns ISPLIT(1)+1 through ISPLIT(2), etc., and
  147.              the NSPLIT-th consists of rows/columns ISPLIT(NSPLIT-1)+1 through
  148.              ISPLIT(NSPLIT)=N.  (Only the first NSPLIT elements will actually
  149.              be used, but since the user cannot know a priori what value
  150.              NSPLIT will have, N words must be reserved for ISPLIT.)
  151.  
  152.      WORK    (workspace) DOUBLE PRECISION array, dimension (4*N)
  153.  
  154.      IWORK   (workspace) INTEGER array, dimension (3*N)
  155.  
  156.      INFO    (output) INTEGER
  157.              = 0:  successful exit
  158.              < 0:  if INFO = -i, the i-th argument had an illegal value
  159.              > 0:  some or all of the eigenvalues failed to converge or
  160.              were not computed:
  161.              =1 or 3: Bisection failed to converge for some eigenvalues; these
  162.              eigenvalues are flagged by a negative block number.  The effect
  163.              is that the eigenvalues may not be as accurate as the absolute
  164.              and relative tolerances.  This is generally caused by
  165.              unexpectedly inaccurate arithmetic.  =2 or 3: RANGE='I' only: Not
  166.              all of the eigenvalues
  167.              IL:IU were found.
  168.              Effect: M < IU+1-IL
  169.              Cause:  non-monotonic arithmetic, causing the Sturm sequence to
  170.              be non-monotonic.  Cure:   recalculate, using RANGE='A', and pick
  171.              out eigenvalues IL:IU.  In some cases, increasing the PARAMETER
  172.              "FUDGE" may make things work.  = 4:    RANGE='I', and the
  173.              Gershgorin interval initially used was too small.  No eigenvalues
  174.              were computed.  Probable cause: your machine has sloppy
  175.              floating-point arithmetic.  Cure: Increase the PARAMETER "FUDGE",
  176.              recompile, and try again.
  177.  
  178. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  179.      RELFAC  DOUBLE PRECISION, default = 2.0e0
  180.              The relative tolerance.  An interval (a,b] lies within "relative
  181.              tolerance" if  b-a < RELFAC*ulp*max(|a|,|b|), where "ulp" is the
  182.              machine precision (distance from 1 to the next larger floating
  183.              point number.)
  184.  
  185.      FUDGE   DOUBLE PRECISION, default = 2
  186.              A "fudge factor" to widen the Gershgorin intervals.  Ideally, a
  187.              value of 1 should work, but on machines with sloppy arithmetic,
  188.              this needs to be larger.  The default for publicly released
  189.              versions should be large enough to handle the worst machine
  190.              around.  Note that this has no effect on accuracy of the
  191.              solution.
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDSSSSTTTTEEEEBBBBZZZZ((((3333SSSS))))                                                          DDDDSSSSTTTTEEEEBBBBZZZZ((((3333SSSS))))
  203.  
  204.  
  205.  
  206. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  207.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  208.  
  209.      This man page is available only online.
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.